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FOREWORD 


The  FORTH  GRAPHICS  TOOLBOX  is  to  be  used  to  develop  FORTH  based  application 
software,  ^his  document  is  intended  to  provide  a  manual  detailing  the  procedures  and 
usage. 

This  document  has  been  reviewed  by  the  users  in  the  Simulation  and  Training  Section 
for  its  technical  integrity  and  the  Underwater  Signal  Processing  Branch's  line  management 
for  elements  of  format  and  style. 

The  GRAPHICS  TOOLBOX  has  evolved  over  a  period  of  two  years  with  input  from 
many  users.  The  author  would  like  to  extend  his  thanks  to  several  people  for  their  input. 
Kit  Yan  is  credited  with  the  development  of  many  graphics  routines  at  the  beginning  of  this 
project;  the  entire  project  was  made  much  easier  because  of  the  strong  foundation  laid  out 
initiall3r  by  Yan.  Bob  Davis,  Phil  Craun,  and  Paul  Craun  provided  much  useful  technical 
insight  in  the  development  of  this  document.  Finally,  Ira  Rosenbaum,  MarkWilliams,  Bob 
Otte,  and  John  Sherman  provided  the  encouragement  to  the  author  in  pursuing  this  project. 

If  you  have  questions  or  comments  about  the  'TOOLBOX,  please  contact  U25  (Hanseok 
Ko),  (301)394-2372.  Comments  are  welcome  and  will  be  considered  when  the  TOOLBOX  is 
revised. 


Approved  by: 


C.  Kalivretenos,  Deputy  Department  Head 
Underwater  Systems  Department 
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CHAPTER  1 
INTRODUCTION 

FORTH  GRAPHICS  TOOLBOX  is  a  rich  collection  of  graphics  routines  immediately 
useful  for  all  FORTH-based  application  software  running  on  IBM-PC  clone  microcomputers. 
The  routines  are  built  based  on  graphics  related  primitives  of  both  video  BIOS  call  functions 
and  Direct-video  functions.  The  user  can  develop  more  exotic  application  software  based  on 
the  routines  listed  in  this  package. 

The  central  features  of  the  FORTH  GRAPHICS  TOOLBOX  are  functions  for: 

•  Video  screen  environment  setup. 

•  Direct  and  BIOS  called  video  drawing  of  a  point,  a  line,  and  a  circle. 

•  Direct  and  BIOS  called  drawing  application. 

•  Demonstration  of  the  package's  graphics  capabilities. 

These  functions  are  implemented  in  the  FORTH  environment  under  the  file  name 
GRAPHICS.SEQ.  Accessing  this  file  will  allow  the  user  to  make  changes,  add  features,  or  . 
learn  how  a  given  algorithm  works.  New  application  routines  can  be  developed  easily  by 
first  loading  GRAPHICS.SEQ  and  experimenting  with  the  application  SEQ-files. 

The  GRAPHICS  TOOLBOX  has  evolved  over  a  period  of  2  years  with  input  from  many 
users,  including  those  mentioned  in  the  Foreword. 
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CHAPTER  2 
INSTALLATION 

FORTH  GRAPHICS  TOOLBOX  can  be  installed  by  first  getting  into  RFF  FORTH 
working  space.  RFF’  is  a  16-bit  FORTH  system  built  upon  the  work  of  several  people:  the 
original  F83  system  by  Laxen  and  Perry,  the  "FF”  system  by  Tom  Zinuner  et.  al.,  and 
numerous  contributions  of  Robert  Davis.  FORTH^  is  a  language  that  begins  with  a 
powerful  set  of  standard  commands,  then  provides  the  mechanism  by  which  a  user  can 
define  his/her  own  commands.  The  structured  process  of  building  definitions  upon  previous 
definitions  is  the  FORTH  equivalent  of  high-level  coding.  Alternatively,  words  may  be 
defined  directly  in  assembler  mnemonics,  using  FORTH’s  assembler.  All  commands  are 
interpreted  by  the  same  interpreter  and  compiled  by  the  same  compiler.  The  user  can  get 
into  the  RFF  FORTH  environment  by  typing  ’RFF’  from  a  directory  containing  the 
‘RFF.EXE’file. 

Once  in  the  RFF  FORTH  environment,  type: 

FLOAD  GRAPHICS 

to  load  GRAPHICS.SEQ.  After  GRAPHICS.SEQ  is  loaded,  test  it  by  invoking  a 
demonstration  graphics  routine  such  as ’TELLIPSE.”  Upon  invoking  "TELLIPSE”,  the 
user  should  see  random  sets  of  different  colored  concentric  rings  displayed  on  the  screen. 
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CHAPTER  3 

HOW  TO  READ  THE  TOOLBOX 

Each  routine  or  function,  presented  in  Reference  A,  is  tagged  as  either  CODE  or 
WORD.  CODE  implies  that  it  is  an  assembly  routine  that  exists  because  it  is  either  a  BIOS 
called  function  or  an  attempt  to  save  processing  time.  WORD  implies  that  it  is  colon  (:) 
defined  and  structured  in  order  to  get  the  full  advantage  of  the  FORTH  environment. 
"Category”  is  listed  to  provide  a  quick  reference  to  the  routine's  background  such  as 
whether  it  is  a  direct  video  or  BIOS  called  function. 

A  stack  diagram  is  provided  adjacent  to  the  name  of  each  routine  in  the  parenthesis. 
For  example,  the  first  line  for  routine  LINE  looks  like  this: 

LINE  (  xl  yl  x2  y2  color  #  -  -  ) 

The  order  of  inputs  typed  onto  the  screen  is  important  since  it  determines  the  inputs' 
respective  positions  on  the  stack.  In  the  above  case,  the  computer  performs  the  operation  in 
accordance  to  the  task  defined  by  LINE  by  either  pushing  or  popping  the  numbers  on  the 
stack.  The  FORTH's  stack  is  described  as  "last-in,  first-out"  (LIFO).  This  means  that  the 
only  accessible  value  at  any  given  time  is  the  top  value.  The  system  reads  input  from  left  to 
right  and  executes  each  word  in  turn.  For  input,  the  rightmost  value  on  the  screen  will  end 
up  on  top  of  the  stack.  For  output,  the  rightmost  value  on  the  screen  came  from  the  lowest 
position  on  the  non-empty  column  of  the  stack.  The  order  of  inputs  with  respect  to  the  top  of 
the  stack,  for  the  LINE  routine,  is  as  follows: 
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top  of  stack 


FIGURE  3-1.  FORTH  STACK  DIAGRAM 


If  a  numerical  output  is  desired,  the  corresponding  output  variables  are  listed  to  the 
right  of  the  dash  (-)  in  the  stack  diagram.  But  if  no  output  variable  is  listed,  as  in  the  case 
of  LINE  routine,  then  an  action  on  the  hardware  such  as  "drawing”  is  expected  as  the 
output. 


The  ranges  of  the  legitimate  numerical  values  are  indicated  in  the  Description  block. 
Most  values  must  be  given  as  integers;  however,  some  routines  require  real  numbers  as 
input.  When  real  numbers  are  required,  the  input  variables  in  the  stack  diagram  will  be 
denoted  by  a  decimal  point  as  shown  below. 


AUTOSCALE  ( xl.  x2.  x  y  color  npt  hv  -  ) 

In  general,  there  are  two  categories  of  graphic  routines:  the  direct- video  and  the  BIOS 
call.  The  BIOS  call  routines  are  denoted  by  a  " _ BIOS  ”  postfix  attached  to  the  syntax  of 
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the  direct-video  counterparts.  For  example,  direct-video's  AST  routine  has  BIOS  call 
counterpart  AST _ BIOS  which  is  invoked  with  software  interrupt  lOH. 

The  direct- video  routines  are  at  least  10  times  faster  than  the  BIOS  call  routines  in 
getting  the  corresponding  image  on  the  screen.  However,  the  BIOS  call  routines  may 
become  handy  if  there  is  a  mismatch  between  the  direct-video  routines  and  the  display  mode 
type.  For  example,  a  progreim  using  only  BIOS  function  calls  for  video  output  will  run  in 
almost  any  MS-DOS  environment,  regardless  of  the  video  hardware,  including  (but  not 
limited  to)  the  entire  IBM  PC  and  PS/2  family. 


The  available  colors  are  simple  combinations  of  the  primary  colors  red,  green,  and  blue 
mapped  into  16  colors  as  follows: 
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CHAPTER  4 

FORTH  GRAPHICS  TOOLBOX 
REFERENCE 


This  chapter  contains  a  listing  of  all  FORTH  Graphics  Toolbox  routines  grouped  by 
subject,  listed  in  alphabetical  order,  and  followed  by  a  brief  description  of  the  routine. 


TABLE  4- 1 .  VIDEO  SCREEN  ENVIRONMENT  SETUP  ROUTINES 


VIDEO  SCREEN  ENVIRONMENT  SETUP  ROUTINES 

AND  VIDEO 

Latched  pixels  ADed 

CGA  HI 

640x200  2-color  CGA 

COSO 

Switch  to  text  mode 

EGA  HI 

640x350  16-color  EGA 

EGA  LO 

640x200  16-color  EGA 

SxSFONT 

Set  8-pixel  font 

8xl4FONT 

Set  14-pixel  font 

SxlSFONT 

Set  16-pixel  font 

NORMAL  VIDEO 

Latched  pixels  replaced 

OR  VIDEO 

Latched  pixels  ORed 

SET  GRAPHMODE 

Set  the  screen  to  VGA/EG A/CG A  etc. 

XOR  VIDEO 

Latched  pixels  XORed 

VGA  HI 

640x480  16-color  VGA 

NAVSWC  MP  91-404 

TABLE  4-2.  DIRECT  VIDEO  DRAWING  COMMANDS 


DIRECT  VIDEO  DRAWING  COMMANDS 

AND  VIDEO 

Latched  pixels  ADed 

ELLIPSE 

Draws  an  ellipse/circle 

HORIZ  LINE 

Draws  an  horizontal  staight  line 

LINE 

Draws  a  stght  line  of  any  orientation 

VERT  LINE 

Draws  a  vertical  straight  line 

CHRPLOT 

Plot  a  character 

TABLE  4-3.  BIOS  CALLED  VIDEO  DRAWING  COMMANDS 


BIOS  CALLED  VIDEO  DRAWING  COMMANDS 

ELLIPSE  BIOS 

Draws  an  ellipse/circle 

HORIZ  LINE  BIOS 

Draws  an  horizontal  staight  line 

LINE  BIOS 

Draws  a  stght  line  of  any  orientation 

PUT  PIXEL 

Plot  a  point 

VERT  LINE  BIOS 

Draws  a  vertical  straight  line 

CHRPLOT  BIOS 

Plot  a  character 

TABLE  4-4.  DIRECT  VIDEO  DRAWING  APPLICATION  COMMANDS 


DIRECT  VIDEO  DRAWING  APPUCATION  COMMANDS 

AUTOSCALE 

Draws  a  scale  with  tick  marks 

OUTTEXTXY 

Plot  a  string  of  characters 

SIGPLOTB 

Plot  a  string  of  characters 
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TABLE  4-5.  BIOS  CALLED  VIDEO  DRAWING  APPUCATION  COMMANDS 


BIOS  CALLED  VIDEO  DRAWING  APPUCATION  COMMANDS 


AUTOSCALE _ BIOS  Draws  a  scale  with  tick  marks 

OUTTEXTXY BIOS  Plot  a  string  of  characters 


TABLE  4-6.  DIRECT  VIDEO  DEMO  ROUTINES 


DIRECT  VIDEO  DEMO  ROUTINES 

AMERICA 

Writes  texts  in  graphics  mode 

AST 

Draws  a  set  of  scales  with  tick  marks 

FIREWORKl 

Draws  random  flashes  of  fireballs 

FIREWORKS 

Draws  random  flashes  of  fireballs 

TELLEPSE 

Draws  random  sets  of  rings 

TUNE 

Draws  random  sets  of  lines 

TXT 

Writes  texts  in  four  orientations 

TABLE  4-7.  BIOS  CALLED  VIDEO  DEMO  ROUTINES 


BIOS  CALLED  VIDEO  DEMO  ROUTINES 

AMERICA  BIOS 

Writes  texts  in  graphics  mode 

AST  BIOS 

Draws  a  set  of  scales  with  tick  marks 

FIREWORK2 

Draws  random  flashes  of  fireballs 

TUNE  BIOS 

Draws  random  sets  of  lines 

TXT  BIOS 

Writes  texts  in  four  orientations 
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TABLE  4-8.  BIOS  FUNCTION  CALLS 


BIOS  FUNCTION  CALLS 

FONTAD  Get  FONT  address  within  EGAATGA 

GET GRAPHMODE  Get  info  about  current  graphic  mode 

GET ^PIXEL  Read  color  info  at  (x,y)  pixel  location 

GET _ XY  Read  current  cursor  position 

GOTO XY  Move  cursor  to  (x,y)  position 

PUT_PIXEL  Plot  a  point  at  (x,y)  pixel  location 

READ _ CHAR  Read  character  at  current  cursor  position 

SCROLL  PAGEDOWN  Scroll  texts  top  to  bottom  on  screen 

SCROLL _ PAGEUP  Scroll  texts  bottom  to  top  on  screen 

SET _ ACTIVEPAGE  Select  a  page  as  active  page  for  graphics 

SET _ BORDER  Draw  a  border  line 

SET GRAPHMODE  Set  the  screen  to  various  graphics  modes 

SET_PALETT  Change  palette's  color  entry  to  new  color 

WRITE _ CHAR  Put  character  at  current  cursor  position 

WRITE _ TCHAR  Put  character  at  current  cursor  position  and 

move  cursor  to  next  position 
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APPENDIX  A 

FORTH  GRAPHICS  TOOLBOX 
FUNCTIONAL  DESCRIPTION 
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Category:  Aaseafcly  code  subroutine  needed  for  direct-video 
graphics  routines 
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